<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
    <title>Importing Feeds - Zend Framework Manual</title>

    <link href="../css/shCore.css" rel="stylesheet" type="text/css" />
    <link href="../css/shThemeDefault.css" rel="stylesheet" type="text/css" />
    <link href="../css/styles.css" media="all" rel="stylesheet" type="text/css" />
</head>
<body>
<h1>Zend Framework</h1>
<h2>Programmer's Reference Guide</h2>
<ul>
    <li><a href="../en/zend.feed.importing.html">Inglês (English)</a></li>
    <li><a href="../pt-br/zend.feed.importing.html">Português Brasileiro (Brazilian Portuguese)</a></li>
</ul>
<table width="100%">
    <tr valign="top">
        <td width="85%">
            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.feed.introduction.html">Introduction</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.feed.html">Zend_Feed</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.feed.findFeeds.html">Retrieving Feeds from Web Pages</a></div>
                    </td>
                </tr>
            </table>
<hr />
<div id="zend.feed.importing" class="section"><div class="info"><h1 class="title">Importing Feeds</h1></div>
    

    <p class="para">
        <span class="classname">Zend_Feed</span> enables developers to retrieve feeds very easily. If you
        know the <acronym class="acronym">URI</acronym> of a feed, simply use the
         <span class="methodname">Zend_Feed::import()</span> method:
    </p>

    <pre class="programlisting brush: php">
$feed = Zend_Feed::import(&#039;http://feeds.example.com/feedName&#039;);
</pre>


    <p class="para">
        You can also use <span class="classname">Zend_Feed</span> to fetch the contents of a feed from a
        file or the contents of a <acronym class="acronym">PHP</acronym> string variable:
    </p>

    <pre class="programlisting brush: php">
// importing a feed from a text file
$feedFromFile = Zend_Feed::importFile(&#039;feed.xml&#039;);

// importing a feed from a PHP string variable
$feedFromPHP = Zend_Feed::importString($feedString);
</pre>


    <p class="para">
        In each of the examples above, an object of a class that extends
        <span class="classname">Zend_Feed_Abstract</span> is returned upon success, depending on the type of
        the feed. If an <acronym class="acronym">RSS</acronym> feed were retrieved via one of the import methods
        above, then a <span class="classname">Zend_Feed_Rss</span> object would be returned. On the other
        hand, if an Atom feed were imported, then a <span class="classname">Zend_Feed_Atom</span> object is
        returned. The import methods will also throw a <span class="classname">Zend_Feed_Exception</span>
        object upon failure, such as an unreadable or malformed feed.
    </p>

    <div class="section" id="zend.feed.importing.custom"><div class="info"><h1 class="title">Custom feeds</h1></div>
        

        <p class="para">
            <span class="classname">Zend_Feed</span> enables developers to create custom feeds very easily.
            You just have to create an array and to import it with <span class="classname">Zend_Feed</span>.
            This array can be imported with  <span class="methodname">Zend_Feed::importArray()</span> or
            with  <span class="methodname">Zend_Feed::importBuilder()</span>. In this last case the array
            will be computed on the fly by a custom data source implementing
            <span class="classname">Zend_Feed_Builder_Interface</span>.
        </p>

        <div class="section" id="zend.feed.importing.custom.importarray"><div class="info"><h1 class="title">Importing a custom array</h1></div>
            

            <pre class="programlisting brush: php">
// importing a feed from an array
$atomFeedFromArray = Zend_Feed::importArray($array);

// the following line is equivalent to the above;
// by default a Zend_Feed_Atom instance is returned
$atomFeedFromArray = Zend_Feed::importArray($array, &#039;atom&#039;);

// importing a rss feed from an array
$rssFeedFromArray = Zend_Feed::importArray($array, &#039;rss&#039;);
</pre>


            <p class="para">
                The format of the array must conform to this structure:
            </p>

            <pre class="programlisting brush: php">
array(
    //required
    &#039;title&#039; =&gt; &#039;title of the feed&#039;,
    &#039;link&#039;  =&gt; &#039;canonical url to the feed&#039;,

    // optional
    &#039;lastUpdate&#039; =&gt; &#039;timestamp of the update date&#039;,
    &#039;published&#039;  =&gt; &#039;timestamp of the publication date&#039;,

    // required
    &#039;charset&#039; =&gt; &#039;charset of the textual data&#039;,

    // optional
    &#039;description&#039; =&gt; &#039;short description of the feed&#039;,
    &#039;author&#039;      =&gt; &#039;author/publisher of the feed&#039;,
    &#039;email&#039;       =&gt; &#039;email of the author&#039;,

    // optional, ignored if atom is used
    &#039;webmaster&#039; =&gt; &#039;email address for person responsible &#039;
                .  &#039;for technical issues&#039;,

    // optional
    &#039;copyright&#039; =&gt; &#039;copyright notice&#039;,
    &#039;image&#039;     =&gt; &#039;url to image&#039;,
    &#039;generator&#039; =&gt; &#039;generator&#039;,
    &#039;language&#039;  =&gt; &#039;language the feed is written in&#039;,

    // optional, ignored if atom is used
    &#039;ttl&#039;    =&gt; &#039;how long in minutes a feed can be cached &#039;
             .  &#039;before refreshing&#039;,
    &#039;rating&#039; =&gt; &#039;The PICS rating for the channel.&#039;,

    // optional, ignored if atom is used
    // a cloud to be notified of updates
    &#039;cloud&#039;       =&gt; array(
        // required
        &#039;domain&#039; =&gt; &#039;domain of the cloud, e.g. rpc.sys.com&#039;,

        // optional, defaults to 80
        &#039;port&#039; =&gt; &#039;port to connect to&#039;,

        // required
        &#039;path&#039;              =&gt; &#039;path of the cloud, e.g. /RPC2&#039;,
        &#039;registerProcedure&#039; =&gt; &#039;procedure to call, e.g. myCloud.rssPlsNotify&#039;,
        &#039;protocol&#039;          =&gt; &#039;protocol to use, e.g. soap or xml-rpc&#039;
    ),

    // optional, ignored if atom is used
    // a text input box that can be displayed with the feed
    &#039;textInput&#039;   =&gt; array(
        // required
        &#039;title&#039;       =&gt; &#039;label of the Submit button in the text input area&#039;,
        &#039;description&#039; =&gt; &#039;explains the text input area&#039;,
        &#039;name&#039;        =&gt; &#039;the name of the text object in the text input area&#039;,
        &#039;link&#039;        =&gt; &#039;URL of the CGI script processing text input requests&#039;
    ),

    // optional, ignored if atom is used
    // Hint telling aggregators which hours they can skip
    &#039;skipHours&#039; =&gt; array(
        // up to 24 rows whose value is a number between 0 and 23
        // e.g 13 (1pm)
        &#039;hour in 24 format&#039;
    ),

    // optional, ignored if atom is used
    // Hint telling aggregators which days they can skip
    &#039;skipDays &#039; =&gt; array(
        // up to 7 rows whose value is
        // Monday, Tuesday, Wednesday, Thursday, Friday, Saturday or Sunday
        // e.g Monday
        &#039;a day to skip&#039;
    ),

    // optional, ignored if atom is used
    // Itunes extension data
    &#039;itunes&#039; =&gt; array(
        // optional, default to the main author value
        &#039;author&#039; =&gt; &#039;Artist column&#039;,

        // optional, default to the main author value
        // Owner of the podcast
        &#039;owner&#039; =&gt; array(
            &#039;name&#039;  =&gt; &#039;name of the owner&#039;,
            &#039;email&#039; =&gt; &#039;email of the owner&#039;
        ),

        // optional, default to the main image value
        &#039;image&#039; =&gt; &#039;album/podcast art&#039;,

        // optional, default to the main description value
        &#039;subtitle&#039; =&gt; &#039;short description&#039;,
        &#039;summary&#039;  =&gt; &#039;longer description&#039;,

        // optional
        &#039;block&#039; =&gt; &#039;Prevent an episode from appearing (yes|no)&#039;,

        // required, Category column and in iTunes Music Store Browse
        &#039;category&#039; =&gt; array(
            // up to 3 rows
            array(
                // required
                &#039;main&#039; =&gt; &#039;main category&#039;,

                // optional
                &#039;sub&#039;  =&gt; &#039;sub category&#039;
            )
        ),

        // optional
        &#039;explicit&#039;     =&gt; &#039;parental advisory graphic (yes|no|clean)&#039;,
        &#039;keywords&#039;     =&gt; &#039;a comma separated list of 12 keywords maximum&#039;,
        &#039;new-feed-url&#039; =&gt; &#039;used to inform iTunes of new feed URL location&#039;
    ),

    &#039;entries&#039; =&gt; array(
        array(
            //required
            &#039;title&#039; =&gt; &#039;title of the feed entry&#039;,
            &#039;link&#039;  =&gt; &#039;url to a feed entry&#039;,

            // required, only text, no html
            &#039;description&#039; =&gt; &#039;short version of a feed entry&#039;,

            // optional
            &#039;guid&#039; =&gt; &#039;id of the article, &#039;
                   .  &#039;if not given link value will used&#039;,

            // optional, can contain html
            &#039;content&#039; =&gt; &#039;long version&#039;,

            // optional
            &#039;lastUpdate&#039; =&gt; &#039;timestamp of the publication date&#039;,
            &#039;comments&#039;   =&gt; &#039;comments page of the feed entry&#039;,
            &#039;commentRss&#039; =&gt; &#039;the feed url of the associated comments&#039;,

            // optional, original source of the feed entry
            &#039;source&#039; =&gt; array(
                // required
                &#039;title&#039; =&gt; &#039;title of the original source&#039;,
                &#039;url&#039;   =&gt; &#039;url of the original source&#039;
            ),

            // optional, list of the attached categories
            &#039;category&#039; =&gt; array(
                array(
                    // required
                    &#039;term&#039; =&gt; &#039;first category label&#039;,

                    // optional
                    &#039;scheme&#039; =&gt; &#039;url that identifies a categorization scheme&#039;
                ),

                array(
                    // data for the second category and so on
                )
            ),

            // optional, list of the enclosures of the feed entry
            &#039;enclosure&#039;    =&gt; array(
                array(
                    // required
                    &#039;url&#039; =&gt; &#039;url of the linked enclosure&#039;,

                    // optional
                    &#039;type&#039; =&gt; &#039;mime type of the enclosure&#039;,
                    &#039;length&#039; =&gt; &#039;length of the linked content in octets&#039;
                ),

                array(
                    //data for the second enclosure and so on
                )
            )
        ),

        array(
            //data for the second entry and so on
        )
    )
);
</pre>


            <p class="para">
                References:
            </p>

            <ul class="itemizedlist">
                <li class="listitem">
                    <p class="para">
                        <acronym class="acronym">RSS</acronym> 2.0 specification: <a href="http://blogs.law.harvard.edu/tech/rss" class="link external">&raquo; RSS 2.0</a>
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                        Atom specification: <a href="http://tools.ietf.org/html/rfc4287" class="link external">&raquo; RFC 4287</a>
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                        <acronym class="acronym">WFW</acronym> specification: <a href="http://wellformedweb.org/news/wfw_namespace_elements" class="link external">&raquo; Well
                            Formed Web</a>
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                        iTunes specification: <a href="http://www.apple.com/itunes/store/podcaststechspecs.html" class="link external">&raquo; iTunes
                            Technical Specifications</a>
                    </p>
                </li>
            </ul>
        </div>

        <div class="section" id="zend.feed.importing.custom.importbuilder"><div class="info"><h1 class="title">Importing a custom data source</h1></div>
            

            <p class="para">
                You can create a <span class="classname">Zeed_Feed</span> instance from any data source
                implementing <span class="classname">Zend_Feed_Builder_Interface</span>. You just have to
                implement the  <span class="methodname">getHeader()</span> and
                 <span class="methodname">getEntries()</span> methods to be able to use your object with
                 <span class="methodname">Zend_Feed::importBuilder()</span>. As a simple reference
                implementation, you can use <span class="classname">Zend_Feed_Builder</span>, which takes
                an array in its constructor, performs some minor validation, and then can be used
                in the  <span class="methodname">importBuilder()</span> method. The
                 <span class="methodname">getHeader()</span> method must return an instance of
                <span class="classname">Zend_Feed_Builder_Header</span>, and
                 <span class="methodname">getEntries()</span> must return an array of
                <span class="classname">Zend_Feed_Builder_Entry</span> instances.
            </p>

            <blockquote class="note"><p><b class="note">Note</b>: 
                <p class="para">
                    <span class="classname">Zend_Feed_Builder</span> serves as a concrete implementation to
                    demonstrate the usage. Users are encouraged to make their own classes to
                    implement <span class="classname">Zend_Feed_Builder_Interface</span>.
                </p>
            </p></blockquote>

            <p class="para">
                Here is an example of  <span class="methodname">Zend_Feed::importBuilder()</span> usage:
            </p>

            <pre class="programlisting brush: php">
// importing a feed from a custom builder source
$atomFeedFromArray =
    Zend_Feed::importBuilder(new Zend_Feed_Builder($array));

// the following line is equivalent to the above;
// by default a Zend_Feed_Atom instance is returned
$atomFeedFromArray =
    Zend_Feed::importBuilder(new Zend_Feed_Builder($array), &#039;atom&#039;);

// importing a rss feed from a custom builder array
$rssFeedFromArray =
    Zend_Feed::importBuilder(new Zend_Feed_Builder($array), &#039;rss&#039;);
</pre>

        </div>

        <div class="section" id="zend.feed.importing.custom.dump"><div class="info"><h1 class="title">Dumping the contents of a feed</h1></div>
            

            <p class="para">
                To dump the contents of a <span class="classname">Zend_Feed_Abstract</span> instance, you
                may use  <span class="methodname">send()</span> or  <span class="methodname">saveXml()</span>
                methods.
            </p>

            <pre class="programlisting brush: php">
assert($feed instanceof Zend_Feed_Abstract);

// dump the feed to standard output
print $feed-&gt;saveXML();

// send http headers and dump the feed
$feed-&gt;send();
</pre>

        </div>
    </div>
</div>
        <hr />

            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.feed.introduction.html">Introduction</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.feed.html">Zend_Feed</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.feed.findFeeds.html">Retrieving Feeds from Web Pages</a></div>
                    </td>
                </tr>
            </table>
</td>
        <td style="font-size: smaller;" width="15%"> <style type="text/css">
#leftbar {
	float: left;
	width: 186px;
	padding: 5px;
	font-size: smaller;
}
ul.toc {
	margin: 0px 5px 5px 5px;
	padding: 0px;
}
ul.toc li {
	font-size: 85%;
	margin: 1px 0 1px 1px;
	padding: 1px 0 1px 11px;
	list-style-type: none;
	background-repeat: no-repeat;
	background-position: center left;
}
ul.toc li.header {
	font-size: 115%;
	padding: 5px 0px 5px 11px;
	border-bottom: 1px solid #cccccc;
	margin-bottom: 5px;
}
ul.toc li.active {
	font-weight: bold;
}
ul.toc li a {
	text-decoration: none;
}
ul.toc li a:hover {
	text-decoration: underline;
}
</style>
 <ul class="toc">
  <li class="header home"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="reference.html">Zend Framework Reference</a></li>
  <li class="header up"><a href="zend.feed.html">Zend_Feed</a></li>
  <li><a href="zend.feed.introduction.html">Introduction</a></li>
  <li class="active"><a href="zend.feed.importing.html">Importing Feeds</a></li>
  <li><a href="zend.feed.findFeeds.html">Retrieving Feeds from Web Pages</a></li>
  <li><a href="zend.feed.consuming-rss.html">Consuming an RSS Feed</a></li>
  <li><a href="zend.feed.consuming-atom.html">Consuming an Atom Feed</a></li>
  <li><a href="zend.feed.consuming-atom-single-entry.html">Consuming a Single Atom Entry</a></li>
  <li><a href="zend.feed.modifying-feed.html">Modifying Feed and Entry structures</a></li>
  <li><a href="zend.feed.custom-feed.html">Custom Feed and Entry Classes</a></li>
  <li><a href="zend.feed.reader.html">Zend_Feed_Reader</a></li>
  <li><a href="zend.feed.writer.html">Zend_Feed_Writer</a></li>
  <li><a href="zend.feed.pubsubhubbub.introduction.html">Zend_Feed_Pubsubhubbub</a></li>
 </ul>
 </td>
    </tr>
</table>

<script type="text/javascript" src="../js/shCore.js"></script>
<script type="text/javascript" src="../js/shAutoloader.js"></script>
<script type="text/javascript" src="../js/main.js"></script>

</body>
</html>